QuickTime 3 Reference

Settings Container Format and Guidelines

The particular atoms stored within the component's settings QTAtomContainer are private to that component type. However, there are some guidelines that need to be followed. These include

In all SetSettingsFromAtomContainer routines, the QTAtomContainer belongs to the caller. The component should not dispose of the QTAtomContainer.
The settings QTAtomContainer should contain one or more top-level atoms. These top-level atoms can contain either leaf data or other atoms. Each atom has both a type (a QTAtomType) and an ID. Choosing an atom type that is mnemonic is helpful in indicating how it is used. For example, QuickTime stores video compression settings in atoms of type `vide'. Sound compression settings are stored in `soun' atoms. The text components use `text' for their atom types.
Several of QuickTime's export components use Standard Compression to allow the user to configure compression settings for exported files. When one of these components is asked to return its settings atom container, the export component first requests that the Standard Compression component return its settings using the SCGetSettingsAsAtomContainer function described above. To the QTAtomContainer it receives, the export component adds any of its own settings. When the export component's SetSettingsFromAtomContainer is called, the exporter calls SCSetSettingsFromAtomContainer with the passed atom container. The Standard Compression component extracts only those settings it expects, ignoring all other, and configures itself. The exporter will then look for its own settings in the same atom container and configure itself. This is possible because both Standard Compression and data exchange components both use QTAtomContainers to hold their settings. Since third-party developers will likely do similarly, there must be a mechanism, so that QuickTime's own top-level atom types and those of third parties don't collide. To achieve this, Apple Computer reserves all top-level atom types consisting exclusively of all lowercase letters with or without numbers. As a consequence, `vide' is reserved by Apple, but `Vide' is not. There is no restriction on the atom types for atoms stored within these top-level atoms.
Apple recommends that you store all of your component settings under a single top-level atom. However, there is no requirement to do so.
The data within an atom should be stored in a canonical form on all platforms. It should either be in big-endian format always or in little-endian format always. Different types of atoms can be stored in different endian orders but for a single type of atom, it should always use the same endianism. This allows the settings to be created on a Macintosh and read on a Windows PC or created on a PC and read on a Macintosh.
In either MovieImportSetSettingsFromAtomContainer or MovieExportSetSettingsFromAtomContainer , you should not necessarily expect all atoms to be included in the atom container you receive. This allows another developer, for example, to create a settings atom container, add atoms and data for only those parts of the settings that should be changed, and then pass this incomplete atom container to the component. The component then will only change those particular settings--leaving other settings alone. QuickTime's own components use this approach.
If nil is passed for the settings to the component routines, return paramErr.
If your component does not have configurable settings, you do not need to implement the settings-related routines.